home *** CD-ROM | disk | FTP | other *** search
/ ETO Development Tools 2 / ETO Development Tools 2.iso / Essentials / Developer Essentials Nov 90 / Apple II / Apple.II.partition / Tools / Technical.Notes / IIGS / TN.IIGS.086 < prev    next >
Encoding:
Text File  |  1990-09-21  |  8.0 KB  |  171 lines  |  [TEXT/pdos]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6. Apple IIgs
  7. #86:    Risking Resourceful Code
  8.  
  9. Written by:    C.K. Haun <TR>                                  September 1990
  10.  
  11. This Technical Note covers considerations you need to keep in mind when using 
  12. code resources.
  13. _____________________________________________________________________________
  14.  
  15. Code resources are wonderful things that can make your life better than it ever 
  16. was before.  Code resources are necessary when writing CDevs and can be very 
  17. useful for control definition procedures, code modules for extensible programs 
  18. like resource editors--in fact, almost anywhere where you use regular compiled 
  19. and linked code.  But to do it right, you need to keep some rules in mind.
  20.  
  21.  
  22. Apple's Code, Apple's Rules
  23.  
  24. The first code resources covered are the ones defined as fully supported by the 
  25. System Software.  These are rCtlDefProc ($800C), rCodeResource ($8017), and 
  26. rCDEVCode ($8018).  Before looking at the specifics, this Note describes in 
  27. general terms what happens when the Resource Manager loads a code resource.
  28.  
  29. When you call the Resource Manager with a request for a code resource (or when 
  30. the system does, as with rCtlDefProcs ), it loads it like a normal resource.  
  31. The Resource Manager finds the resource in a resource map in the current search 
  32. path, allocates a handle for the resource using the attributes in the resource 
  33. attribute bits, and loads the resource into memory.
  34.  
  35. Now the Resource Manager examines the resConverter bit in the resource header.  
  36. If this bit is set, indicating that this resource needs to be converted (as it 
  37. should be for an rCtlDefProc), the Resource Manager checks its tables to see if 
  38. a resource converter has been logged in (with the ResourceConverter call).  For 
  39. code resources, the correct converter has been logged in by the manager 
  40. associated with that resource type.  For example, the Control Manager logs in 
  41. the code resource converter for rCtlDefProc resource type.
  42.  
  43. For code resources,  InitialLoad2 is used to load the OMF from memory.  Then the 
  44. Resource Manager returns a handle containing a pointer to the start of the 
  45. loaded, relocated code.
  46.  
  47. Rule 1:    Code resources must be smaller than 64K
  48.  
  49. The code resource converter uses the InitialLoad2 function of the System Loader 
  50. to load and convert code resources.  That means that code resources are 
  51. restricted in the same way that loading from memory is. One of these 
  52. restrictions is that the code must be 64K or less.
  53.  
  54.  
  55. Rule 2:    Compiled and linked code only
  56.  
  57. Again, since InitialLoad2 is used to convert the code resource, the data must 
  58. be in OMF format since  InitialLoad2 expects to relocate standard load 
  59. segments.  When you prepare your code for inclusion in a code resource, compile 
  60. and link the code as you normally would for a stand-alone program.  Use the 
  61. file produced by the linker for inclusion in your resource fork.  You can use 
  62. Rez to move the code from a data fork to your application's resource fork with 
  63. a line in your resource description file similar to the following:
  64.  
  65. read rCodeResource (MyCodeIDNumber,locked,convert)  "MyCompiledAndLinkedCode";
  66.  
  67. Rule 3:    One segment please
  68.  
  69. Multiple segments are theoretically possible with code resources, but you have 
  70. to manage memory IDs and the memory that the additional code segments use 
  71. yourself.  Since the code resource converter calls InitialLoad2, it uses the 
  72. Memory Manager ID for the current resource application, and you cannot specify 
  73. a different user ID directly.  By changing your current resource application ID 
  74. (by making an additional call to ResourceStartUp with a modified master ID, for 
  75. example) you could manage multisegment code resources.
  76.  
  77. Rule 4:    No dynamic segments
  78.  
  79. The dynamic segment mechanism does not work with code resources.  Of course, 
  80. your application can still use dynamic segments, but not code resource dynamic 
  81. segments.
  82.  
  83. Rule 5:    Set the right attributes
  84.  
  85. There are two sets of attributes you need to be concerned about for a code 
  86. resource.  The first set includes the standard resource attributes; the second 
  87. set covers the attributes that the code itself has in the OMF image.
  88.  
  89. You need both sets to get the functionality you want.  The resource attributes 
  90. determine how the Resource Manager handles the resource.  The OMF attributes 
  91. control what InitialLoad2 does when it converts your code from OMF in a resource 
  92. handle to relocated executable code.
  93.  
  94. Remember, you need to set both sets of attributes.
  95.  
  96. The resource attributes you need to set are locked and convert.  The locked 
  97. flag is necessary to prevent the resource from moving while InitialLoad2 
  98. processes it, and the convert flag is needed to signal the Resource Manager to 
  99. call the code resource converter.
  100.  
  101. You must set the static OMF attribute, the others (like no special memory) you 
  102. set as appropriate for your code in your application.
  103.  
  104. Rule 6:    Know where to go
  105.  
  106. The handle you get back from the Resource Manager when you load and convert a 
  107. code resource points to the beginning of the relocated and ready-to-execute 
  108. code, not to the image of the code that is stored in the resource fork.  So you 
  109. can immediately jump to this code to execute it.
  110.  
  111. You can override this if you like--clear the resConverter bit in the resource 
  112. attributes.  If this bit is zero, the Resource Manager does not call any 
  113. resource converter (including the code resource converter).
  114.  
  115. Rule 7:    Remember the Write
  116.  
  117. Keep in mind that any resource that uses a converter uses that converter both 
  118. for reading and writing the resource.  If you write out a code resource, the 
  119. Resource Manager calls the Write routine for the code resource converter, which 
  120. currently writes without doing any conversion--it does not reconvert the code 
  121. in memory back to OMF format.    However, some converters (perhaps one you 
  122. write) could reconvert the resource before writing it out.
  123.  
  124.  
  125. Your Code, Your Rules
  126.  
  127. If you want to define your own code resource type (with a resource type of less 
  128. than $8000 and greater than 0) you may want to follow the same rules as the 
  129. system code resources use.  In fact, you can even use the same code resource 
  130. converter, by using the ResourceConverter call with your resource type, and log 
  131. the code resource converter as the converter to use with your resource type, 
  132. like the following:
  133.  
  134.        pha
  135.        pha                     ; return space
  136.        _GetCodeResConverter    ; Misc Tools call to return the loader 
  137. *                              ; relocation code pointer
  138. *                              ; (leave it on the stack for the next call)
  139.        pea $0678               ; resource type you want to convert with this 
  140. *                              ; converter, any
  141. *                              ; Application type you wish
  142.        pea %01                 ; add this converter to the Application 
  143. *                              ;converter list,
  144. *                              ; and log this routine in 
  145.        _ResourceConverter
  146.  
  147. or you can do whatever you like with the resource, including not having a 
  148. converter and doing all the relocation and memory management of the code 
  149. yourself.  This can give you the ability to add more functionality than the 
  150. standard code resources provide--dynamic segmentation is one feature you could 
  151. implement if you want to handle all the details yourself.
  152.  
  153. Or, you can manage the code any way you want, but keep the built-in system 
  154. functions in mind, and use as many of them as you can.  Make your life simpler.
  155.  
  156.  
  157. One Final Note
  158.  
  159. If one of your resources is marked convert and preload the Resource Manager 
  160. only preloads that resource if the converter for that resource is logged in as 
  161. a converter for that type.  If the Resource Manager cannot find the converter, 
  162. it does not preload the resource. 
  163.  
  164.  
  165. Further Reference
  166. _____________________________________________________________________________
  167.   o  Apple IIgs Toolbox Reference, Volume 3
  168.   o  GS/OS Reference
  169.   o  Apple IIgs Sample Code #9, Lister
  170.  
  171.